// 版权所有2009年围棋作者。版权所有。
// 此源代码的使用受BSD样式的约束
// 可以在许可证文件中找到的许可证。

package gob

import (
	"bufio"
	"errors"
	"io"
	"reflect"
	"sync"
)

// tooBig为尺寸提供了一个健全的检查；在几个地方使用。上限
// 在32位系统上，of是1GB，在64位系统上是8GB，这允许空间稍微增长
// 没有溢出。
const tooBig = (1 << 30) << (^uint(0) >> 62)

// 解码器管理从解码器读取的类型和数据信息的接收
// 连接的远程端。多个用户同时使用是安全的
// 戈罗季斯。
// None
// 解码器仅对解码的输入大小进行基本的健全性检查，
// 其限制是不可配置的。解码gob数据时要小心
// 来自不可信的来源。
type Decoder struct {
	mutex        sync.Mutex                              // 每个项目必须按原子顺序接收
	r            io.Reader                               // 数据来源
	buf          decBuffer                               // 缓冲区用于从r进行更高效的i/o
	wireType     map[typeId]*wireType                    // 从远程ID映射到本地描述
	decoderCache map[reflect.Type]map[typeId]**decEngine // 编译引擎的缓存
	ignorerCache map[typeId]**decEngine                  // 被忽略对象同上
	freeList     *decoderState                           // 免费解码状态列表；避免重新分配
	countBuf     []byte                                  // 用于解析消息时解码整数
	err          error
}

// NewDecoder返回从io.Reader读取的新解码器。
// 如果r不同时实现io.ByteReader，它将被包装在
// bufio.Reader。
func NewDecoder(r io.Reader) *Decoder {
	dec := new(Decoder)
	// 我们使用读取字节的能力作为缓冲的合理替代。
	if _, ok := r.(io.ByteReader); !ok {
		r = bufio.NewReader(r)
	}
	dec.r = r
	dec.wireType = make(map[typeId]*wireType)
	dec.decoderCache = make(map[reflect.Type]map[typeId]**decEngine)
	dec.ignorerCache = make(map[typeId]**decEngine)
	dec.countBuf = make([]byte, 9) // 计数可能是uint64s（不太可能！），需要9个字节

	return dec
}

// recvType加载类型的定义。
func (dec *Decoder) recvType(id typeId) {
	// 我们已经见过这种类型了吗？那是个错误
	if id < firstUserId || dec.wireType[id] != nil {
		dec.err = errors.New("gob: duplicate type received")
		return
	}

	// 类型：
	wire := new(wireType)
	dec.decodeValue(tWireType, reflect.ValueOf(wire))
	if dec.err != nil {
		return
	}
	// 记住我们见过这种类型。
	dec.wireType[id] = wire
}

var errBadCount = errors.New("invalid message length")

// RecVMMessage从输入中读取下一个计数分隔项。恰恰相反
// Encoder.writeMessage的。它在EOF或读取消息时返回false。
func (dec *Decoder) recvMessage() bool {
	// 数一数。
	nbytes, _, err := decodeUintReader(dec.r, dec.countBuf)
	if err != nil {
		dec.err = err
		return false
	}
	if nbytes >= tooBig {
		dec.err = errBadCount
		return false
	}
	dec.readMessage(int(nbytes))
	return dec.err == nil
}

// readMessage从输入中读取下一个N字节。
func (dec *Decoder) readMessage(nbytes int) {
	if dec.buf.Len() != 0 {
		// 缓冲区现在应该总是空的。
		panic("non-empty decoder buffer")
	}
	// 读取数据
	dec.buf.Size(nbytes)
	_, dec.err = io.ReadFull(dec.r, dec.buf.Bytes())
	if dec.err == io.EOF {
		dec.err = io.ErrUnexpectedEOF
	}
}

// toInt根据封送规则将编码的uint64转换为int。
func toInt(x uint64) int64 {
	i := int64(x >> 1)
	if x&1 != 0 {
		i = ^i
	}
	return i
}

func (dec *Decoder) nextInt() int64 {
	n, _, err := decodeUintReader(&dec.buf, dec.countBuf)
	if err != nil {
		dec.err = err
	}
	return toInt(n)
}

func (dec *Decoder) nextUint() uint64 {
	n, _, err := decodeUintReader(&dec.buf, dec.countBuf)
	if err != nil {
		dec.err = err
	}
	return n
}

// decodeTypeSequence解析：
// 类型序列
// （TypeDefinition DelimitedTypeDefinition*）？
// 并返回下一个值的类型id。它以-1的速度返回
// EOF。返回时，dec.buf的剩余部分是要返回的值
// 解码。如果这是一个接口值，则可以忽略它
// 重置缓冲区。
func (dec *Decoder) decodeTypeSequence(isInterface bool) typeId {
	for dec.err == nil {
		if dec.buf.Len() == 0 {
			if !dec.recvMessage() {
				break
			}
		}
		// 接收类型id。
		id := typeId(dec.nextInt())
		if id >= 0 {
			// 价值观如下。
			return id
		}
		// （-id）的类型定义如下。
		dec.recvType(-id)
		if dec.err != nil {
			break
		}
		// 当解码一个接口时，在一个类型之后可能有一个
		// DelimitedValue仍在缓冲区中。跳过它的计数。
		// （或者，缓冲区为空，字节计数
		// 将被recvMessage吸收。）
		if dec.buf.Len() > 0 {
			if !isInterface {
				dec.err = errors.New("extra data in buffer")
				break
			}
			dec.nextUint()
		}
	}
	return -1
}

// 解码从输入流读取下一个值并存储
// 它位于由空接口值表示的数据中。
// 如果e为nil，则该值将被丢弃。否则
// 基础e的值必须是指向
// 接收到的下一个数据项的正确类型。
// 如果输入为EOF，解码返回io.EOF和
// 不修改e。
func (dec *Decoder) Decode(e interface{}) error {
	if e == nil {
		return dec.DecodeValue(reflect.Value{})
	}
	value := reflect.ValueOf(e)
	// 如果e代表一个与指针相反的值，则答案不会
	// 回到打电话的人那里。确保它是指针。
	if value.Type().Kind() != reflect.Ptr {
		dec.err = errors.New("gob: attempt to decode into a non-pointer")
		return dec.err
	}
	return dec.DecodeValue(value)
}

// DecodeValue从输入流中读取下一个值。
// 如果v是零reflect.Value（v.Kind（）==无效），DecodeValue将丢弃该值。
// 否则，它将值存储到v中。在这种情况下，v必须表示
// 指向数据或可赋值的reflect.Value（v.CanSet（））的非nil指针
// 如果输入为EOF，DecodeValue返回io.EOF和
// 不修改v。
func (dec *Decoder) DecodeValue(v reflect.Value) error {
	if v.IsValid() {
		if v.Kind() == reflect.Ptr && !v.IsNil() {
			// 没关系，我们将通过指针进行存储。
		} else if !v.CanSet() {
			return errors.New("gob: DecodeValue of unassignable value")
		}
	}
	// 确保我们在这里是单线程的。
	dec.mutex.Lock()
	defer dec.mutex.Unlock()

	dec.buf.Reset() // 以防上一次调用的数据延迟。
	dec.err = nil
	id := dec.decodeTypeSequence(false)
	if dec.err == nil {
		dec.decodeValue(id, v)
	}
	return dec.err
}

// 如果debug.go被编译到程序中，debugFunc将打印一个可读的
// 通过调用r文件的调试函数来表示从r读取的gob数据。
// 否则为零。
var debugFunc func(io.Reader)
